npm-package-arg

What is npm-package-arg?

The npm-package-arg package is a utility for parsing package names and specifiers in the npm ecosystem. It helps in understanding and manipulating package references, whether they are simple names, version ranges, GitHub URLs, or local paths.

What are npm-package-arg's main functionalities?

Parsing Package Names

This feature allows you to parse a simple package name. The output will be an object containing details about the package, such as its name, type, and registry.

const npa = require('npm-package-arg');
const parsed = npa('express');
console.log(parsed);

Parsing Version Ranges

This feature allows you to parse a package name with a version range. The output will include the specified version range and other details.

const npa = require('npm-package-arg');
const parsed = npa('express@^4.0.0');
console.log(parsed);

Parsing GitHub URLs

This feature allows you to parse a GitHub URL. The output will include details about the repository, such as the user and repo names.

const npa = require('npm-package-arg');
const parsed = npa('github:user/repo');
console.log(parsed);

Parsing Local Paths

This feature allows you to parse a local file path. The output will include details about the local path and the type of reference.

const npa = require('npm-package-arg');
const parsed = npa('file:./local-package');
console.log(parsed);

Other packages similar to npm-package-arg

validate-npm-package-name

The validate-npm-package-name package is used to validate whether a string is a valid npm package name. Unlike npm-package-arg, it focuses solely on validation and does not parse version ranges, URLs, or paths.

semver

The semver package is used for parsing, validating, and comparing semantic versioning strings. While npm-package-arg can parse version ranges as part of a package specifier, semver provides more comprehensive tools for working with version numbers.

npm-registry-fetch

The npm-registry-fetch package is used to make requests to the npm registry. It can fetch package metadata and tarballs. While npm-package-arg helps in parsing package specifiers, npm-registry-fetch is focused on interacting with the npm registry.

README

npm-package-arg

Parse package name and specifier passed to commands like npm install or npm cache add. This just parses the text given-- it's worth noting that npm has further logic it applies by looking at your disk to figure out what ambiguous specifiers are. If you want that logic, please see realize-package-specifier.

Arguments look like: foo@1.2, @bar/foo@1.2, foo@user/foo, http://x.com/foo.tgz, git+https://github.com/user/foo, bitbucket:user/foo, foo.tar.gz or bar

EXAMPLES

var assert = require("assert")
var npa = require("npm-package-arg")

// Pass in the descriptor, and it'll return an object
var parsed = npa("@bar/foo@1.2")

// Returns an object like:
{
  raw: '@bar/foo@1.2',       // what was passed in
  name: '@bar/foo',          // the name of the package
  escapedName: '@bar%2ffoo', // the escaped name, for making requests against a registry
  scope: '@bar',             // the scope of the package, or null
  type: 'range',             // the type of specifier this is
  spec: '>=1.2.0 <1.3.0',    // the expanded specifier
  rawSpec: '1.2'             // the specifier as passed in
 }

// Parsing urls pointing at hosted git services produces a variation:
var parsed = npa("git+https://github.com/user/foo")

// Returns an object like:
{
  raw: 'git+https://github.com/user/foo',
  scope: null,
  name: null,
  escapedName: null,
  rawSpec: 'git+https://github.com/user/foo',
  spec: 'user/foo',
  type: 'hosted',
  hosted: {
    type: 'github',
    ssh: '[e-mail]:user/foo.git',
    sshurl: 'git+ssh://[e-mail]/user/foo.git',
    https: 'https://github.com/user/foo.git',
    directUrl: 'https://raw.githubusercontent.com/user/foo/master/package.json'
  }
}

// Completely unreasonable invalid garbage throws an error
// Make sure you wrap this in a try/catch if you have not
// already sanitized the inputs!
assert.throws(function() {
  npa("this is not \0 a valid package name or url")
})

USING

var npa = require('npm-package-arg')

• var result = npa(arg)

Parses arg and returns a result object detailing what arg is.

arg -- a package descriptor, like: foo@1.2, or foo@user/foo, or http://x.com/foo.tgz, or git+https://github.com/user/foo

RESULT OBJECT

The objects that are returned by npm-package-arg contain the following keys:

• name - If known, the name field expected in the resulting pkg.
• type - One of the following strings:
  • git - A git repo
  • hosted - A hosted project, from github, bitbucket or gitlab. Originally either a full url pointing at one of these services or a shorthand like user/project or github:user/project for github or bitbucket:user/project for bitbucket.
  • tag - A tagged version, like "foo@latest"
  • version - A specific version number, like "foo@1.2.3"
  • range - A version range, like "foo@2.x"
  • local - A local file or folder path
  • remote - An http url (presumably to a tgz)
• spec - The "thing". URL, the range, git repo, etc.
• hosted - If type=hosted this will be an object with the following keys:
  • type - github, bitbucket or gitlab
  • ssh - The ssh path for this git repo
  • sshUrl - The ssh URL for this git repo
  • httpsUrl - The HTTPS URL for this git repo
  • directUrl - The URL for the package.json in this git repo
• raw - The original un-modified string that was provided.
• rawSpec - The part after the name@..., as it was originally provided.
• scope - If a name is something like @org/module then the scope field will be set to @org. If it doesn't have a scoped name, then scope is null.
• escapedName - A version of name escaped to match the npm scoped packages specification. Mostly used when making requests against a registry. When name is null, escapedName will also be null.

If you only include a name and no specifier part, eg, foo or foo@ then a default of latest will be used (as of 4.1.0). This is contrast with previous behavior where * was used.